perm filename FUNCTI.17[CLS,LSP] blob
sn#834371 filedate 1987-02-12 generic text, type T, neo UTF8
\input macros
\drafttrue
\def\bookline{\CLOS\ Specification}
\def\chapline{Functions in the Programmer Interface}
\beginChapter 2.{Common Lisp Object System Specification}%
{Functions in the Programmer Interface}{Functions in the Programmer Interface}
This document was written by Daniel G. Bobrow, Linda G. DeMichiel,\break
Richard P. Gabriel, Sonya Keene, Gregor Kiczales, and David A. Moon.
Contributors to this document include Patrick Dussud, Kenneth Kahn,\break
Larry Masinter, Mark Stefik,
Daniel L. Weinreb, and Jon L White.
\endTitlePage
\beginSection{Introduction}
This chapter describes the functions provided by the \CLOS\
Programmer Interface. The Programmer Interface comprises the set of
functions and macros that are sufficient for writing most object-oriented
programs.
The description of each function includes its purpose, its syntax, the
semantics of its arguments and returned values, and often an example
and cross-references to related functions. This chapter is reference
material that requires an understanding of the basic concepts of the
Common Lisp Object System. The functions are arranged in alphabetic
order for convenient reference.
It is useful to categorize the functions and macros according to their
role in this standard:
\Vskip 2pc!
\beginlist
\item{\bull}
{Tools used for simple object-oriented programming}
These tools allow for defining new classes, methods, and generic
functions, and for making instances. Some tools used within the body
of methods are also listed here. Some of the macros listed here have
a corresponding function that performs the same task at a lower level of
abstraction.
{\bf defclass}\break
{\bf make-instance}\break
{\bf defmethod}\break
{\bf defmethod-setf}\break
{\bf defgeneric-options}\break
{\bf defgeneric-options-setf}\break
{\bf call-next-method}\break
{\bf slot-value}\break
{\bf with-slots}\break
{\bf change-class}\break
{\bf class-changed}\break
\item{\bull}
{Functions underlying the commonly-used macros}
{\bf add-method}\break
{\bf get-method}\break
{\bf get-setf-generic-function}\break
{\bf make-generic-function}\break
{\bf make-method}\break
{\bf remove-method}\break
\eject
\item{\bull}
{Tools for declarative method combination}
{\bf define-method-combination}\break
{\bf make-method-call}\break
{\bf method-qualifiers}\break
{\bf multiple-value-prog2}\break
{\bf method-combination-error}\break
{\bf invalid-method-error}\break
\item{\bull}
{General Common Lisp support tools}
{\bf class-of}\break
{\bf describe}\break
{\bf documentation}\break
{\bf print-object}\break
\endlist
\vfill
\endSection%{Introduction}
\begincom{add-method}\ftype{Generic function}
\label Purpose:
The generic function {\bf add-method} adds a method to a generic
function. It destructively modifies the generic function and returns
the modified generic function as its result.
\label Syntax:
\Defgen {add-method} {generic-function method}
\label Arguments:
The {\it generic-function\/} argument is a generic function
object.
The {\it method\/} argument is a method object. The lambda-list of
the method function must be congruent with the lambda-lists of any
other methods associated with the generic function and with the
lambda-list of the generic function.
\label Values:
The generic function {\bf add-method} returns the modified generic function.
\label Remarks:
If the given method is already one of the methods of the generic
function or if the method corresponds in parameter specializers and
method qualifiers to an existing method of the generic
function, an error is signaled.
%Note that a given method may be a method on more than one generic
%function.
\label See Also:
{\bf defmethod
make-method
make-generic-function
defgeneric-options}
\endcom
\begincom{call-next-method}\ftype{Function}
\label Purpose:
The binding for the local function variable {\bf call-next-method} has
lexical scope and dynamic extent. The function {\bf call-next-method}
is used within the body of a method to call the next method. The next
method is called with the same arguments that were received by the
method in which {\bf call-next-method} is invoked. The function {\bf
call-next-method} returns the value or values returned by the method
it calls. If there is no next method, an error is signaled.
The type of method combination used determines which
methods can invoke {\bf call-next-method}. The standard method
combination type allows {\bf call-next-method} to be used within primary
methods and {\bf :around} methods. It defines the next method as
follows:
\beginlist
\item{\bull}
If {\bf call-next-method} is used in an {\bf :around} method,
the next method is the next most specific {\bf :around} method, if one is
applicable.
\item{\bull}
If there are no {\bf :around} methods at all or if {\bf
call-next-method} is called by the least specific {\bf :around}
method, other methods are called as follows:
\itemitem{--} All the {\bf :before} methods are called, in
most specific first order. Their values are ignored.
\itemitem{--}
The most specific primary method is called. Inside the body of a
primary method, {\bf call-next-method} may be used to pass control
to the next most specific primary method. An error is signaled if {\bf
call-next-method} is used and there is no applicable primary method.
\itemitem{--} All the {\bf :after} methods are called in
most specific last order. Their values are ignored.
\endlist
\label Syntax:
\Defun {call-next-method} {}
\label Arguments:
The function {\bf call-next-method} is used with no arguments.
\label Values:
The function {\bf call-next-method} returns the value or values
returned by the method it calls.
\label Remarks:
The function {\bf call-next-method} passes the current method's
original arguments to the next method. Neither argument defaulting,
nor using {\bf setq}, nor rebinding variables with the same
names as parameters of the method affects the values {\bf call-next-method}
passes to the method it calls.
Further computation is possible after {\bf call-next-method} returns.
If the short form of {\bf define-method-combination} is used to define
a new type of method combination, {\bf call-next-method} can be used
in {\bf :around} methods only.
A proposed extension is to allow {\bf call-next-method} to accept
arguments. When arguments are given, {\bf call-next-method} invokes
the next method on those arguments instead of the arguments that were received
by the method from which it is called.
\label See Also:
``Method Selection and Combination''
``Standard Method Combination''
{\bf define-method-combination}
\endcom
\begincom{change-class}\ftype{Function}
\label Purpose:
The function {\bf change-class} changes the class of an instance to a
new class. It destructively modifies and returns the instance. The
values of local slots held in common between the old and new class are
preserved in the new instance. The other slots are initialized as
described in the section ``Redefining Classes.'' The generic function
{\bf class-changed} is run.
\label Syntax:
\Defun {change-class} {instance new-class}
\label Arguments:
The {\it instance\/} argument is a Lisp object, although
not all objects are required to allow {\bf change-class}.
The {\it new-class\/} argument is a class object or a symbol that names
a class.
\label Values:
The modified instance is returned. The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.
\label Examples:
\screen!
(defclass position () ())
(defclass x-y-position (position)
((x :initform 0)
(y :initform 0))
(:accessor-prefix position-))
(defclass rho-theta-position (position)
((rho :initform 0)
(theta :initform 0))
(:accessor-prefix position-))
(defmethod class-changed ((old x-y-position)
(new rho-theta-position))
;; Copy the position information from old to new to make new
;; be a rho-theta-position at the same position as old.
(let ((x (position-x old))
(y (position-y old)))
(setf (position-rho new) (atan y x)
(position-theta new) (sqrt (+ (* x x) (* y y))))))
;;; At this point an instance of the class x-y-position can be
;;; changed to be an instance of the class rho-theta-position using
;;; change-class:
(setq p1 (make-instance 'x-y-position :x 2 :y 0))
(change-class p1 'rho-theta-position)
;;; The result is that the instance bound to p1 is now an instance of
;;; the class rho-theta-position. The method for class-changed
;;; performed the initializion of the rho and theta slots based
;;; on the value of the x and y slots, which were maintained by
;;; the old instance.
\endscreen!
\label Remarks:
The \CLOS\ requires {\bf change-class} to apply in only the following case:
let $C\sub 1$ and $C\sub 2$ be classes that are defined by {\bf
defclass} without using the {\bf :metaclass} option in either case; let
$X$ be an instance of $C\sub 1$. Then, the class of $X$ can be changed
from $C\sub 1$ to $C\sub 2$. Both before and after the call to {\bf
change-class}, the metaclass of $X$ is the default metaclass, namely
{\bf standard-class}.
Implementors can choose to support {\bf change-class} in additional
cases. For example, this standard does not require that
{\bf change-class} be able to accept an instance of a standard type class
as its first argument or a standard type class as its second argument;
however, it is valid for an implementation to support this for some
standard type classes.
If {\bf change-class} is applied to arguments that are not supported by
the implementation, an error is signaled.
After completing all other actions, {\bf change-class} invokes the generic
function {\bf class-changed}. The generic function {\bf class-changed}
can be used to reinitialize slots.
The function {\bf change-class} has several semantic difficulties.
First, it performs a destructive operation that can be invoked within a
method on an instance that was used to select that method. When multiple
methods are involved because methods are being combined, the problem
could be compounded. Second, some implementations might use compiler
optimizations of slot access and when the class of an instance is
changed, the assumptions the compiler made might be violated.
This implies that an application programmer must not use {\bf
change-class} inside a method if any methods for that generic function
access any slots.
\eject
\label See Also:
``Redefining Classes''
{\bf class-changed}
\endcom
\begincom{class-changed}\ftype{Generic Function}
\label Purpose:
The generic function {\bf class-changed} is not intended to be called
by programmers. Programmers are expected to write methods for it.
The generic function {\bf change-class} is invoked automatically by
the system after {\bf defclass} has been used to redefine an existing
class. It can also be explicitly invoked by the user.
\label Syntax:
\Defgen {class-changed} {previous current}
\label Arguments:
When {\bf change-class} is invoked on an instance, a copy of that instance
is made; {\bf change-class} then destructively alters the original instance.
The first argument to {\bf class-changed}, {\it previous\/}, is that copy,
and the second argument, {\it current}, is the altered original instance.
The typical use of {\it previous\/} is to extract old slot values by using
{\bf slot-value} or {\bf with-slots} or by invoking an accessor generic
function. Any function, generic or not, can receive the value passed as
{\it previous\/} as an argument.
\label Values:
The value returned by {\bf class-changed} is ignored by {\bf change-class}.
\label Examples:
See the example for the function {\bf change-class}.
\label Remarks:
Methods on {\bf class-changed} must be defined by using {\bf add-method}
and {\bf make-method}. It is not possible to define methods on {\bf
class-changed} by using {\bf defmethod}.
The arguments to {\bf class-changed} are computed by {\bf change-class}.
The first argument is a copy of the argument to {\bf change-class}; this
argument has dynamic extent within {\bf change-class}, and therefore it
is an error to reference any part of it once {\bf change-class} returns.
The default method for {\bf class-changed} does nothing. Methods on
{\bf class-changed} can be defined to initialize slots differently from
{\bf change-class}. In this
way {\bf class-changed} methods can alter the default behavior of {\bf
change-class} with respect to slot value preservation. The default
behavior is described in ``Redefining Classes.''
The generic function {\bf class-changed} uses standard method
combination; thus {\bf :before}, {\bf :after}, {\bf :around}, and
unqualified methods are allowed.
\eject
\label See Also:
``Redefining Classes''
{\bf change-class
add-method
make-method}
\endcom
\begincom{class-named}\ftype{Function}
\label Purpose:
The function {\bf class-named} returns the class named by a given
symbol.
\label Syntax:
\Defun {class-named} {name {\opt} errorp}
\label Arguments:
The first argument to {\bf class-named} is a symbol.
If there is no class named by the symbol and the {\it errorp\/} argument is
unsupplied or is non-{\bf nil}, {\bf class-named} signals an error.
If there is no class named by the symbol and the second argument is
{\bf nil}, {\bf class-named} returns {\bf nil}. The default value of
{\it errorp\/} is {\bf t}.
\label Values:
The result of {\bf class-named} is the class named by the given symbol.
\endcom
\begincom{class-of}\ftype{Function}
\label Purpose:
The function {\bf class-of} returns the class object for the most
specific class of which the given object is an instance. Every Common
Lisp object has a class.
\label Syntax:
\Defun {class-of} {object}
\label Arguments:
The argument to {\bf class-of} may be any Common Lisp object.
\label Values:
The function {\bf class-of} returns the class object that represents the
most specific class of which the argument is an instance.
\label Remarks:
Which Common Lisp types will have corresponding classes is still under
discussion. That decision will affect the behavior of {\bf class-of}.
%If the object was created with a constructor defined by {\bf defstruct},
%the class that is returned is the class with the same name as the data
%type defined with the {\bf defstruct} form.
%If the object is an instance of a class whose class is {\bf
%standard-type-class} or a subclass of {\bf standard-type-class} (other
%than a class created with {\bf defstruct}), the class that is returned
%is the most specific class according to Figure~1-2.
\endcom
\begincom{defclass}\ftype{Macro}
\label Purpose:
The macro {\bf defclass} defines a new class. It returns the name of
the new class as its result.
The syntax of {\bf defclass} provides options for specifying default
initialization values for slots, for requesting that methods for
appropriately named generic functions be automatically generated for
reading and writing the values of slots, and for requesting that a
constructor function be automatically generated for making instances of
the new class. No accessors, readers, or constructor functions are defined
by default; their generation must be explicitly requested.
Defining a new class also causes a type of the same name to be defined.
The predicate {\tt (typep {\it object class-name\/})} is true if the
class of the given object is {\it class-name\/} itself or a subclass
of the class {\it class-name}.
The class object defined by {\bf defclass} is stored in the value cell
of the symbol named {\it class-name}.
\eject
\label Syntax:
\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name} \paren{\star{\curly{superclass-name}}}
\paren{\star{\curly{slot-spec}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it superclass-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-spec\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \star{\curly{slot-option}})\cr
\Vskip 1pc!
\+&{\it slot-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :accessor} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :reader} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type\/} $\vert$ \cr
\+&&{\tt :initform} {\it form\/} $\vert$ \cr
\+&&{\tt :type} {\it type-specifier\/} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessor-prefix} {\it symbol\/}) $\vert$\cr
\+&&({\tt :reader-prefix} {\it symbol\/}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol\/} \brac{boa-arglist\/}) $\vert$\cr
\+&&({\tt :documentation} {\it string\/}) $\vert$ \cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform}{\rm )}}}} \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig
\vfill\eject
\label Arguments:
The {\it class-name\/} argument is a non-{\bf nil} symbol. It becomes the
name of the new class. If a class with the same name already exists, the
definition of that class is replaced.
Each {\it superclass-name\/} argument is a non-{\bf nil} symbol. The
new class will inherit slots and methods from each of its
superclasses, from their superclasses, and so on. See the section
``Inheritance'' for a discussion of how slots and methods are
inherited.
Each {\it slot-spec\/} argument is the name of the slot or a list consisting
of the slot name followed by zero or more slot options. The {\it slot-name\/}
argument is a symbol that can be used as a Common Lisp variable name.
If there are any duplicate slot names, an error is signaled.
The following slot options are available:
\beginlist
\item{\bull}
The {\bf :accessor} option specifies that an unqualified method
is to be defined on the generic function named {\it
generic-function-name\/} to read the value of the given slot and that
an unqualified method is to be defined on the setf generic function named
{\it generic-function-name} to be used with {\bf setf} to modify the
value of the slot. The {\it generic-function-name\/} argument is a
non-{\bf nil} symbol. The {\bf :accessor} option may be specified
more than once for a given slot.
\item{\bull}
The {\bf :reader} option specifies that an unqualified method
is to be defined on the generic function named {\it
generic-function-name\/} to read the value of the given slot. The
{\it generic-function-name\/} argument is a non-{\bf nil} symbol. The
{\bf :reader} option may be specified more than once for a given slot.
\item{\bull}
The {\bf :allocation} option is used to specify where
storage is to be allocated for the given slot. Storage for a slot may
be static or dynamic; it may be located in the class instance or in
the class object itself. The value of the {\it allocation-type\/}
argument can be one of the following keywords: {\bf :instance}, {\bf
:class}, or {\bf :dynamic}. The {\bf :allocation} option may be
specified once at most for a given slot. If the {\bf :allocation}
option is not specified, a local slot of the given name is allocated in
each instance of the class.
\itemitem{--}
If {\it allocation-type\/} is {\bf :instance}, a local slot of the given name
is allocated in each instance of the class.
\itemitem{--}
If {\it allocation-type\/} is {\bf :class}, a shared slot of the given
name is allocated in the class object created by this {\bf defclass}
form. The value of the slot is shared by all instances of the class.
Any subclass of this class will share this single slot unless the {\bf
defclass} form for that subclass specifies a slot of the same name.
\itemitem{--}
If {\it allocation-type\/} is {\bf :dynamic}, a local
slot of the given name is allocated in the instance the first time the
slot is used. This option allows infrequently used slots to occupy
storage only if necessary.
\item{\bull} The {\bf :initform} option is used to provide a default
initial value form to be used in the initialization of the slot. The
{\bf :initform} option may be specified once at most for a given slot.
This form is evaluated every time it is used. The lexical environment
in which this form is evaluated is the lexical environment in which
{\bf defclass} was evaluated. Note that the lexical environment
refers both to variables and to functions. The dynamic environment is
the one in effect at the time the form is evaluated. This is the same
behavior specified for {\bf defstruct} slot initialization forms in
{\it Common Lisp: The Language}.
\item{\bull}
The {\bf :type} option specifies the type of the slot contents. The
expression {\tt ({\tt typep} {\it value type-specifier\/})} will be
true for the value stored in the slot. The {\bf :type} option may be
specified once at most for a given slot. The {\bf :type} option is
further discussed in the section ``Inheritance of Slots and Slot Options.''
\endlist
Each class option is an option that refers to the class as a whole
or to all class slots. The following class options are available:
\beginlist
\item{\bull}
The {\bf :accessor-prefix} option specifies that, for each
slot, an unqualified method to read the value of the slot is to be defined on the
generic function named {\it symbol} followed by the
name of the slot. Similarly, a method to be used with the macro {\bf
setf} to modify the value of the slot is to be defined on the setf
generic function named {\it symbol} followed by the
name of the slot. These accessor functions are interned in the
package that is current at the time the {\bf defclass} form is
macro-expanded. If the prefix is {\bf nil}, the names of the accessor
functions are the symbols that are used as the slot names. The {\bf
:accessor-prefix} option may be specified more than once.
\item{\bull}
The {\bf :reader-prefix} option specifies that, for each slot, an
unqualified method to read the value of the slot is to be defined on the
generic function named {\it symbol} followed by the name of the slot.
These reader functions are interned in the package that is current at
the time the {\bf defclass} form is macro-expanded. If the prefix is
{\bf nil}, the names of the reader functions are the symbols that are
used as the slot names. The {\bf :reader-prefix} option may be
specified more than once.
\item{\bull}
The {\bf :constructor} option causes a constructor function to be
generated automatically. The constructor function is used to make new
instances of the class. The {\it symbol\/} argument is a non-{\bf
nil} symbol that specifies the name of the constructor function. If
the {\it boa-arglist\/} argument is present, it describes the
arguments to the constructor. The {\it boa-arglist\/} argument of
{\bf defclass} is the same as that of {\bf defstruct}. The {\bf
:constructor} option may be specified more than once.
\item{\bull}
The {\bf :documentation} option causes a documentation string to be
attached to the class name. The documentation type for this string is
{\bf type}. The form {\tt (documentation {\it class-name\/} 'type)}
may be used to retrieve the documentation string. The {\bf
:documentation} option may be specified once at most.
\item{\bull}
The {\bf :metaclass} option is used to specify that instances of the
class being defined are to have a different metaclass than the default
provided by the system (the class {\bf standard-class}). The {\it
class-name} argument is the name of the desired metaclass. The {\bf
:metaclass} option may be specified once at most.
\endlist
\eject
\label Values:
The name of the new class is returned as the result.
\label Remarks:
If a class of the same name already exists, that class is redefined
and instances of the class (and subclasses of it) are updated to the
new definition at the time that they are next accessed. For details,
see ``Redefining Classes'' and {\bf change-class}. Redefining a
standard type class is not allowed.
Note the following rules of {\bf defclass}:
\beginlist
\item{\bull}
It is not required that the superclasses of a class be defined before
the {\bf defclass} form for that class is evaluated.
\item{\bull}
All the superclasses of a class must be defined before
an instance of the class can be made.
\item{\bull}
A class must be defined before it can be used as a parameter
specializer in a {\bf defmethod} form.
\item{\bull}
All the superclasses of a class must be defined before
a {\bf with-slots} form that uses that class can be evaluated or compiled.
\endlist
Some slot options are inherited by a class from its
superclasses, and some can be shadowed or altered by providing a
local slot description. No class options are inherited. For a
detailed description of how slots and slot options are inherited,
see the section ``Inheritance of Slots and Slot Options.''
Some implementations might add other options to {\bf defclass}.
Therefore, it is required that all implementations signal an error if
they observe a class option or a slot option that is not implemented
locally.
If no default value for a slot is specified in either a {\bf
defclass} or a {\bf make-instance} form, the initial value of the
slot is unspecified.
It is valid to specify more than one accessor or reader for a slot.
No other slot option may appear more than once in a single slot
description.
The {\bf :accessor-prefix}, {\bf :constructor}, and {\bf :reader-prefix}
class options may appear more than once. No other class option may
appear more than once in a single {\bf defclass} form.
If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value} or by {\bf
with-slots} using {\bf :use-accessors nil}.
\eject
\label See Also:
{\bf slot-value
with-slots}
``Classes''
``Inheritance''
``Redefining Classes''
``Determining the Class Precedence List''
\endcom
\begincom{defgeneric-options}\ftype{Macro}
\label Purpose:
The macro {\bf defgeneric-options} is used to specify options and
declarations that pertain to a generic function as a whole.
The generic function is stored in the function cell of the symbol {\it name}.
If {\tt (fboundp {\it name\/})} is {\bf nil}, a new generic function
is created. If {\tt (symbol-function {\it name\/})} is a generic function,
that generic function is modified. If neither of these conditions holds,
{\bf defgeneric-options} signals an error.
The macro {\bf defgeneric-options} returns {\it name\/} as its result.
\label Syntax:
\Defmac {defgeneric-options} {name lambda-list \star{\curly{option}}}
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order \plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\label Arguments:
The {\it name} argument is a non-{\bf nil} symbol.
The {\it lambda-list\/} argument is an ordinary function lambda-list
with these exceptions:
\beginlist
\item{\bull}
No {\bf \&aux} variables are allowed.
\item{\bull}
Optional and keyword arguments may not have default initial value forms
nor use supplied-p parameters.
The generic function passes to the method all the argument values passed to
it, and only those; default values are not supported.
Note that optional and keyword arguments in method definitions, however,
can have default initial value forms and can use supplied-p parameters.
\endlist
The following options are provided:
\beginlist
\item{\bull}
The {\bf :argument-precedence-order} option is used to specify the
order in which the required arguments in a call to the generic
function are tested for specificity when selecting a particular
method. By default, all required arguments are considered from left
to right; each required argument has precedence over those to its
right. Each required argument must be included exactly once as a {\it
parameter-name} so that the full and unambiguous precedence order is
supplied. If this condition is not met, an error is signaled.
\item{\bull}
The {\bf declare} option is used to specify declarations that pertain
to the generic function. The following standard Common Lisp
declaration is allowed:
\itemitem{--}
An {\bf optimize} declaration specifies whether method selection
should be optimized for speed or space, but it has no effect on methods.
To control how a method is optimized, an {\bf optimize} declaration
must be placed directly in the {\bf defmethod} form. The optimization
qualities {\bf speed} and {\bf space} are the only qualities this
standard requires, but other qualities may be recognized by particular
implementations. A simple implementation that has only one method
selection technique and ignores the {\bf optimize} declaration is
valid.
The {\bf special}, {\bf ftype}, {\bf function}, {\bf inline}, {\bf
notinline}, and {\bf declaration} declarations are not permitted.
Individual implementations can support their own additional
declarations. If an implementation notices a declaration that it does
not support and that has not been proclaimed as a nonstandard
declaration name, it should issue a warning.
\item{\bull}
The {\bf :documentation} argument associates a documentation string
with the generic function. The documentation type for this string is
{\bf function}. The form {\tt (documentation {\it
generic-function-name\/} 'function)} may be used to retrieve this
string.
\item{\bull}
The {\bf :generic-function-class} option may be used to specify that
the generic function is to have a different class than the default
provided by the system (the class {\bf standard-generic-function}).
The {\it class-name\/} argument is the name of a class that can be the
class of a generic function.
\item{\bull}
The {\bf :method-class} option is used to specify that all methods for
this generic function are to have a different class than the default
provided by the system (the class {\bf standard-method}). The {\it
class-name\/} argument is the name of a class that is capable of being
the class of a method.
\item{\bull}
The {\bf :method-combination} option is followed by a symbol that
names a type of method combination. The arguments (if any) that
follow that symbol depend on the type of method combination. Note
that the standard method combination type does not support any
arguments. However, all types of method combination defined by the
short form of {\bf define-method-combination} accept an optional
argument named {\it order\/}, defaulting to {\bf
:most-specific-first}, where a value of {\bf :most-specific-last} reverses
the order of the primary methods, without affecting the order of the
auxiliary methods.
\endlist
\label Values:
The macro {\bf defgeneric-options} returns {\it name\/} as its result.
\label Remarks:
%[What happens when {\bf defgeneric-options} causes the options of an existing
%generic function to be changed needs to be spec'd out.]
%[Note: other kinds of errors still need to be discussed.]
The {\it lambda-list\/} argument of {\bf defgeneric-options} specifies
the shape of lambda-lists for the methods of this generic
function. All methods for the generic function must have lambda-lists
that are congruent with this shape. If a {\bf defgeneric-options}
form is evaluated and some methods for that generic function have
lambda-lists that are not congruent with that given in the {\bf
defgeneric-options} form, an error is signaled. For further details
on method congruence, see ``Congruent Lambda-lists for all Methods of
a Generic Function''
Some implementations might add other options to {\bf defgeneric-options}.
Therefore, it is required that all implementations signal an error if
they observe an option that is not implemented locally.
\label See Also:
``Congruent Lambda-lists for All Methods of a Generic Function''
\endcom
\begincom{defgeneric-options-setf}\ftype{Macro}
\label Purpose:
The macro {\bf defgeneric-options-setf} is used to define a setf
generic function. A setf generic function is called in an
expression such as {\tt (setf ({\it name arguments}) {\it new-value})}.
The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.
\label Syntax:
\Defmac {defgeneric-options-setf} {name lambda-list setf-lambda-list \star{\curly{option}}}
{\it setf-lambda-list\/}::$=$ \paren{variable-name\/}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order \plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{args\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip1pc!\null
\label Arguments:
The {\it name\/} argument is a non-{\bf nil} symbol.
The {\it lambda-list\/} argument is identical to the
{\it lambda-list\/} argument of {\bf defgeneric-options}.
The {\it setf-lambda-list\/} argument is {\tt ({\it variable-name\/})}.
It describes the parameter that receives the {\it new-value\/}
argument to {\bf setf}.
The options are the same as for {\bf defgeneric-options}.
\label Values:
The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.
\label Remarks:
%[The internal operation of this function needs to be spec'd out.
%--Gregor to provide.
%]
The {\it lambda-list\/} argument of {\bf defgeneric-options-setf}
specifies the shape of lambda-lists for the methods of this setf
generic function. All methods for the setf generic function must have
lambda-lists that are congruent with this shape. For further details
on method congruence, see ``Congruent Lambda-lists for All Methods of
a Generic Function''
\label See Also:
{\bf defgeneric-options
defmethod}
``Congruent Lambda-lists for All Methods of a Generic Function''
\endcom
\begincom{define-method-combination}\ftype{Macro}
\label Purpose:
The macro {\bf define-method-combination} is used to define new types
of method combination.
There are two forms of {\bf define-method-combination}. The short
form is a simple facility for the cases that have been found
to be most commonly needed. The long form is more powerful but more
verbose. It resembles {\bf defmacro} in that the body is an
expression, usually using backquote, that computes a Lisp form. Thus
arbitrary control structures can be implemented. The long form also
allows arbitrary processing of method qualifiers.
\label Syntax:
\Defmac {define-method-combination} {name \star{\curly{short-form-option}}}
\Vskip 1pc!
{\it short-form-option\/}::$=$ {\tt\vtop{\hbox{:documentation {\it string\/} $\vert$}
\hbox{:identity-with-one-argument {\it boolean\/} $\vert$}
\hbox{:operator {\it operator\/} $\vert$}
\hbox{:order {\it order\/}}}}
\Vskip1pc!
\Defmac {define-method-combination} {\vtop{\hbox{name lambda-list }
\hbox{\paren{\star{\curly{method-group-specifier}}} }
\hbox{\star{\curly {declaration $\vert$ doc-string}}}
\hbox{\star{\curly{form}}}}}
\vbox
{\halign {\hskip \leftskip#\hfil\hfil\cr
{\it method-group-specifier\/}::$=$ (&{\it variable\/}
\curly{\plus{\curly{qualifier-pattern}} $\vert$ predicate}\cr
&\star{\curly{long-form-option}})\cr}}
\Vskip 1pc!
{\it long-form-option\/}::$=$ {\tt\vtop{\hbox{:description {\it format-string\/} $\vert$}
\hbox{:order {\it order\/} $\vert$}
\hbox{:required {\it boolean\/}}}}
\Vskip1pc!\null
\label Arguments:
In both the short and long forms, {\it name\/} is a symbol. By convention,
non-keyword, non-{\bf nil} symbols are usually used.
\label Arguments of the Short Form:
The short form syntax of {\bf define-method-combination} is recognized
when the second subform is a non-{\bf nil} symbol or is not present.
When the short form is used, {\it name\/} is defined as a type of
method combination that produces a Lisp form {\tt ({\it operator
method-call method-call $\ldots$})}. The {\it operator\/} is a symbol
that can be the name of a function, macro, or special form. The
{\it operator\/} can be specified by a keyword option; it defaults to {\it
name}.
Keyword options for the short form are the following:
\beginlist
\item{\bull}
The {\bf :documentation} option is used to document the method-combination type.
\item{\bull}
The {\bf :identity-with-one-argument} option enables an optimization
when {\it boolean\/} is true (the default is false). If there is
exactly one applicable method and it is a primary method, that method
serves as the effective method and {\it operator\/} is not called.
This optimization avoids the need to create a new effective method and
avoids the overhead of a function call. This option is designed to be
used with operators such as {\bf progn}, {\bf and}, {\bf $+$}, and
{\bf max}.
\item{\bull}
The {\bf :operator} option specifies the name of the operator. The
{\it operator\/} argument is a symbol that can be the name of a
function, macro, or special form. By convention, {\it name\/} and
{\it operator\/} are often the same symbol, but this is not required.
\item{\bull}
The {\bf :order} option specifies the order of methods. The {\it
order\/} argument is a form that evaluates to {\bf
:most-specific-first} or {\bf :most-specific-last}. If it evaluates
to any other value, an error is signaled.
If {\bf :order} is not specified, it defaults to {\bf :most-specific-first}.
\endlist
None of the subforms is evaluated.
A method combination procedure defined in this way recognizes two roles
for methods. An unqualified method is a primary method. A method
with the keyword symbol with the same name as {\it name\/} as its one
qualifier is also defined to be a primary method. Attaching this
qualifier to a primary method documents that this method is intended
for use with an unusual form of method combination and can make
programs easier to understand.
A method with {\bf :around} as its one qualifier is an auxiliary method
that behaves the same as a {\bf :around} method in standard method
combination.
The function {\bf call-next-method} can only be used in {\bf :around}
methods, not in primary methods.
A method combination procedure defined in this way accepts an optional
argument named {\it order}, which defaults to {\bf
:most-specific-first}. A value of {\bf :most-specific-last} reverses
the order of the primary methods without affecting the order of the
auxiliary methods.
A large fraction of the types of method combination needed by
most programmers can be implemented with this short form, which is
provided for convenience. The short form automatically includes
error checking and support for {\bf :around} methods
and avoids the need for the use of the backquote and comma.
\eject
\label Arguments of the Long Form:
The long form syntax of {\bf define-method-combination} is recognized
when the second subform is a list.
The {\it lambda-list\/} argument is an ordinary lambda-list. It
receives any arguments provided after the name of the method
combination type in the {\bf :method-combination} option to {\bf
defgeneric-options} or {\bf defgeneric-options-setf}.
A list of method-group specifiers follows. Each specifier selects a subset
of the applicable methods to play a particular role, either by matching
their qualifiers against some patterns or by testing their qualifiers with
a predicate. These method-group specifiers define all method qualifiers
that can be used with this type of method combination. If an applicable
method does not fall into any method-group, the system reports the error
that the method is invalid for the kind of method combination in use.
Each method-group specifier names a variable. During the execution of
the forms in the body of {\bf define-method-combination}, this
variable is bound to a list of the methods in the method-group. The
methods in this list occur in most-specific-first order.
A qualifier pattern is a list or the symbol {\bf *}. A method matches
a qualifier pattern if the method's list of qualifiers is {\bf equal}
to the qualifier pattern (except that the symbol {\bf *} in a qualifier
pattern matches anything). Thus, a qualifier pattern can be one of the
following: the empty list {\bf ()}, which matches unqualified methods;
the symbol {\bf *}, which matches all methods; a true list, which
matches methods with the same number of qualifiers as the length of
the list when each qualifier matches the corresponding list element;
or a dotted list that ends in the symbol {\bf *} (the {\bf *} matches
any number of additional qualifiers).
Each applicable method is tested against the qualifier patterns and
predicates in left-to-right order. As soon as a qualifier pattern matches
or a predicate returns true, the method becomes a member of the
corresponding method-group and no further tests are made. Thus, if a method
could be a member of more than one method-group, it joins only the first
such group. If a method-group has more than one qualifier pattern, a
method need only satisfy one of the qualifier patterns to be a member of
the group.
The name of a predicate function can appear instead of qualifier
patterns in a method-group specifier. The predicate is called for
each method that has not been assigned to an earlier method-group; it
is called with one argument, the method's qualifier list. The
predicate should return true if the method is to be a member of the
method-group. A predicate can be distinguished from a qualifier pattern
because it is a symbol other than {\bf nil} or {\bf *}.
Method-group specifiers can have keyword options following the
qualifier patterns or predicate. Keyword options can be distinguished from
additional qualifier patterns because they are neither lists nor the symbol
{\bf *}. The keyword options are as follows:
\beginlist
\item{\bull}
The {\bf :description} option is used to provide a description of the
role of methods in the method-group. Programming environment tools
use {\tt (apply \#'format stream {\it format-string\/}
(method-qualifiers {\it method\/}))} to print this description, which
is expected to be concise, that is, one or two words. This keyword
option allows the description of a method qualifier to be defined in
the same module that defines the semantic meaning of the method
qualifier. In most cases, {\it format-string\/} will not contain any
format directives, but they are available for generality. If {\bf
:description} is not specified, a default description is generated
based on the variable name and the qualifier patterns, and on whether this
method-group includes the primary methods; the correct functioning of
automatic description generation depends on the programmer following
the convention that primary methods are bound to the variable named
{\tt primary} in the method-group specifier. The argument {\it
format-string\/} is not evaluated.
\item{\bull}
The {\bf :order} option specifies the order of methods. The {\it
order\/} argument is a form that evaluates to {\bf
:most-specific-first} or {\bf :most-specific-last}. If it evaluates
to any other value, an error is signaled. This keyword option is a
convenience and does not add any expressive power.
If {\bf :order} is not specified, it defaults to {\bf :most-specific-first}.
\item{\bull}
The {\bf :required} option specifies whether at least one method in
this method-group is required. If the {\it boolean\/} argument is
non-{\bf nil} and the method-group is empty (that is, no applicable
methods match the qualifier patterns or satisfy the predicate), an
error is signaled. This keyword option is a convenience and does not
add any expressive power. If {\bf :required} is not specified,
it defaults to {\bf nil}. The {\it boolean\/} argument is not
evaluated.
\endlist
The use of method-group specifiers provides a convenient syntax to
select methods, to divide them among the possible roles, and to perform the
necessary error checking. It is possible to perform further filtering
of methods in the body forms by using normal list-processing operations
and the functions {\bf method-qualifiers} and {\bf
invalid-method-error}. It is permissible to use {\bf setq} on the
variables named in the method-group specifiers and to bind additional
variables. It is also possible to bypass the method-group specifier
mechanism and do everything in the body forms. This is accomplished
by writing a single method group with {\bf *} as its only qualifier
pattern; the variable is then bound to a list of all of the applicable
methods, in most specific first order.
The body {\it forms\/} compute and return the Lisp form that specifies how
the methods are combined, that is, the effective method.
The body of {\bf define-method-combination} resembles the body of
{\bf defmacro} and uses backquote in a similar way.
The function {\bf make-method-call} is also used in constructing the
Lisp form; it hides the implementation-dependent details of how
methods are called. Programmers always use {\bf make-method-call} to
translate from the lists of method objects produced by the method-group
specifiers to Lisp forms that invoke those methods.
Erroneous conditions detected by the body should be reported with
{\bf method-combination-error} or {\bf invalid-method-error}; these functions
add any necessary contextual information to the error message and will
signal the appropriate error.
The body {\it forms\/} are evaluated inside of the bindings created by the
lambda-list and method-group specifiers. Declarations at the head of
the body are positioned directly inside of bindings created by the
lambda-list and outside of the bindings of the method-group variables.
Thus method-group variables cannot be declared.
Within the body {\it forms\/}, the lexical variable {\bf generic-function}
is bound to the generic-function object.
If a {\it doc-string\/} argument is present, it documents the
method-combination type.
The functions {\bf make-method-call}, {\bf method-combination-error}, and
{\bf invalid-method-error} can be called from the body {\it forms\/} or
from functions called by the body {\it forms\/}. The action of these three
functions can depend on dynamic variables automatically bound before
the method combination function is called. These variables might contain the
parameter list of the effective method or other implementation-dependent
information.
Note that two methods with identical specializers, but different
qualifiers, are not ordered by the algorithm described in Step 2 of the
method selection and combination process described in the section
``Method Selection and Combination.'' Normally the two methods
play different roles in the effective method because they have
different qualifiers, and no matter how they are ordered in the
result of Step 2, the effective method is the same. If the two
methods play the same role and their order matters,
implementations are encouraged to signal an error (this would happen
as part of qualifier pattern matching in {\bf
define-method-combination}).
\label Values:
The name of the new method combination type is returned.
\label Examples:
Most examples of the long form of {\bf define-method-combination} also
illustrate the use of the related functions that are provided as part
of the declarative method combination facility.
\screen!
;;; Examples of the short form of define-method-combination
(define-method-combination and :identity-with-one-argument t)
(defmethod func :and ((x class1) y) ...)
;;; The equivalent of this example in the long form is:
(define-method-combination and
(&optional (order ':most-specific-first))
((around (:around))
(primary () (:and) :order order :required t))
(make-method-call `(,@around
,(make-method-call primary
:operator 'and
:identity-with-one-argument t))
:operator :call-next-method))
;;; Examples of the long form of define-method-combination
;The default method-combination technique
(define-method-combination standard ()
((around (:around))
(before (:before))
(primary () :required t)
(after (:after)))
(make-method-call `(,@around
(multiple-value-prog2
,(make-method-call before)
,(make-method-call primary
:operator :call-next-method)
,(make-method-call (reverse after))))
:operator :call-next-method))
;A simple way to try several methods until one returns non-nil
(define-method-combination and ()
((methods () (:and)))
(make-method-call methods :operator 'and))
;A more complete version of the preceding
(define-method-combination and
(&optional (order ':most-specific-first))
((around (:around))
(primary () (:and)))
;; Process the order argument
(case order
(:most-specific-first)
(:most-specific-last (setq primary (reverse primary)))
(otherwise (method-combination-error "~S is an invalid order.~@
:most-specific-first and :most-specific-last are the possible values."
order)))
;; Must have a primary method
(unless primary
(method-combination-error "A primary method is required."))
(make-method-call `(,@around
,(make-method-call primary
:operator 'and
:identity-with-one-argument t))
:operator :call-next-method))
;The same thing, using the :order and :required keyword options
(define-method-combination and
(&optional (order ':most-specific-first))
((around (:around))
(primary () (:and) :order order :required t))
(make-method-call `(,@around
,(make-method-call primary
:operator 'and
:identity-with-one-argument t))
:operator :call-next-method))
;This short-form call is behaviorally identical to the preceding
(define-method-combination and :identity-with-one-argument t)
;Order methods by positive integer qualifiers
;:around methods are disallowed to keep the example small
(define-method-combination example-method-combination ()
((methods positive-integer-qualifier-p))
(make-method-call (stable-sort methods #'<
:key #'(lambda (method)
(first (method-qualifiers method))))))
(defun positive-integer-qualifier-p (method-qualifiers)
(and (= (list-length method-qualifiers) 1)
(typep (first method-qualifiers) '(integer 0 *))))
\endscreen!
\label Remarks:
The {\bf :method-combination} option of
{\bf defgeneric-options} and {\bf defgeneric-options-setf} is used to
specify that a generic function should use a particular method combination
type. The argument to the {\bf :method-combination} option is the name of a
method combination type.
Individual implementations might support other keyword options.
Therefore, it is required that all implementations signal an error if
they observe a keyword option that is not implemented locally.
\label See Also:
{\bf make-method-call}
{\bf method-qualifiers}
{\bf multiple-value-prog2}
{\bf method-combination-error}
{\bf invalid-method-error}
{\bf defgeneric-options
defgeneric-options-setf}
\endcom
\begincom{defmethod}\ftype{Macro}
\label Purpose:
The macro {\bf defmethod} defines a method on a generic function.
If a generic function is currently named by the symbol {\it name\/},
the lambda-list of the method must be congruent with the lambda-list
of the generic function. If this condition does not hold, an error is
signaled. See the section ``Congruent Lambda-lists for All Methods of
a Generic Function'' for a definition of congruence in this context.
If no generic function is currently named by the symbol {\it name\/},
a generic function is created with default values for the argument
precedence order (each argument is more specific than the arguments to
its right in the argument list), for the generic function class (the class
{\bf standard-generic-function}), for the method class (the class {\bf
standard-method}), and for the method combination type (the standard
method combination type). The lambda-list of the generic function is
congruent with the lambda-list of the method being defined.
If the symbol {\it name\/} names a non-generic function, a macro, or a
special form, an error is signaled.
\label Syntax:
\Defmac {defmethod} {name
\vtop{\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it non-nil-atom}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var $\vert$ {\rm (}var parameter-specializer-name\/{\rm )}}} \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}} \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it parameter-specializer-name\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt quote} {\it datum}{\rm )}\cr
\Vskip 1pc!
\label Arguments:
The {\it name\/} argument is a non-{\bf nil} symbol that
names the generic function on which the method is defined.
Each method qualifier is an object that is used by method combination
to identify the given method. A method qualifier is a non-{\bf nil}
atom. The method combination type may further restrict what a method
qualifier may be. The standard method combination type allows for
primary (in this case, unqualified) methods or methods whose sole
qualifier is one of the following keywords: {\bf :before}, {\bf
:after}, or {\bf :around}.
The {\it specialized-lambda-list\/} argument is like an ordinary
function lambda-list except that parameters for required arguments are
replaced by parameter specifiers. A parameter specifier is a list of
the form {\tt ({\it var parameter-specializer-name\/})}. Only
required parameters may be specialized. A parameter specializer name is a
symbol that names a user-defined class, a structure defined by {\bf
defstruct} if the {\bf :type} option was not used, or a class that
corresponds to a Common Lisp type specifier. Note that not all Common
Lisp types have a corresponding class. A parameter specializer name can
also be {\tt (quote {\it object\/})}. Such a parameter specializer name
indicates that the corresponding argument must be {\bf eql} to the
quoted object for the method to be applicable. If no parameter
specializer name is specified for a given required parameter, the parameter
specializer name for that parameter defaults to {\bf t}. A method
whose required parameters all have {\bf t} parameter specializers is termed a
{\bit default method}. Such a method is selected when no more
specific method for the generic function is applicable. See the
section ``Introduction to Methods'' for further discussion.
\label Values:
The result of {\bf defmethod} is the method object.
\label Remarks:
The class of the method object that is created is that given by the
method class option of the generic function on which the method is defined.
If a method already exists on the given generic function with the same
parameter specializers and the same qualifiers, {\bf defmethod} replaces
the existing method with the one now being defined.
The parameter specializers are derived from the parameter specializer
names as described in the section ``Introduction to Methods.''
\label See Also:
{\bf add-method}
``Introduction to Methods''
``Congruent Lambda-lists for all Methods of a Generic Function''
\endcom
\begincom{defmethod-setf}\ftype{Macro}
\label Purpose:
The macro {\bf defmethod-setf} defines a method for a setf generic
function. A setf generic function is called in an expression such as
{\tt (setf ({\it name arguments\/}) {\it new-value\/})}.
\label Syntax:
\Defmac {defmethod-setf} {name
\vtop{\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list specialized-setf-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it non-nil-atom}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var $\vert$ {\rm (}var parameter-specializer-name\/{\rm )}}} \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}} \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specialized-setf-lambda-list\/}::$=$ (\curly{var $\vert$ {\rm (}var specializer\/{\rm ))}} \cr
\Vskip1pc!\null
\+&{\it parameter-specializer-name\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt quote} {\it datum}{\rm )}\cr
\Vskip 1pc!
\label Arguments:
The arguments {\it name\/}, {\it method-qualifier\/}, and {\it
specialized-lambda-list\/} are the same as for {\bf defmethod}.
The {\it specialized-setf-lambda-list\/} argument is the same as {\it
specialized-lambda-list\/} except that for now there can be only one
parameter. In other words, {\it specialized-setf-lambda-list\/} is a
lambda-list containing exactly one required parameter, which may be
specialized.
It describes the parameter that receives the {\it new-value\/}
argument to {\bf setf} in the expression {\tt (setf {\it place
new-value})}.
The {\it var\/} argument in the {\it specialized-setf-lambda-list\/}
argument is the name of the variable that gets bound to the value of
the {\it new-value\/} form in the expression {\tt (setf {\it place
new-value})}.
\label Values:
The result of {\bf defmethod-setf} is the method object.
\label Remarks:
If a method already exists on the given generic function with the same
parameter specializers and the same qualifiers, {\bf defmethod-setf} replaces
the existing method with the one now being defined.
\label See Also:
{\bf defmethod}
\endcom
\begincom{describe}\ftype{Generic function}
\label Purpose:
The Common Lisp function {\bf describe} is replaced by a generic
function. The generic function {\bf describe} prints information
about a given object on the standard output.
Each implementation is required to provide a default method for {\bf
describe}, that is, a method for the class {\bf t}. Implementations
are free to add methods for specific classes. Users can write methods
for {\bf describe} for their own classes if they do not wish to
inherit an implementation-supplied method. These methods must conform
to the definition of {\bf describe} as specified in {\it Common Lisp:
The Language}.
\label Syntax:
\Defgen {describe} {object}
\label Arguments:
The argument of {\bf describe} may be any Common Lisp object.
\label Values:
The generic function {\bf describe} returns no values.
\endcom
\begincom{documentation}\ftype{Generic Function}
\label Purpose:
The Common Lisp function {\bf documentation} is replaced by a generic
function. The generic function {\bf documentation} returns the
documentation string associated with the given object if it is
available; otherwise it returns {\bf nil}.
\label Syntax:
\Defgen documentation {x {\opt} doc-type}
\label Arguments:
The first argument is a generic function object, a method object, a class
object, or a symbol.
If the first argument is not a symbol, the second argument must not be
supplied. If the first argument is a generic function object, method
object, or class object, {\bf documentation} returns the documentation
string for that object.
If the first argument is a symbol, the second argument must be
supplied. The generic function
{\bf documentation} returns the documentation string of
the given type. The {\it doc-type\/} argument is a symbol. It can be
one of the following types: {\bf variable}, {\bf function}, {\bf
structure}, {\bf type}, and {\bf setf}.
If the first argument is a symbol and the second argument is {\bf type},
{\bf documentation} returns the documentation string of the class object
named by the symbol.
If the first argument is a symbol and the second argument is {\bf
function}, {\bf documentation} returns the documentation string of the
function or generic function named by the symbol.
If the first argument is a symbol and the second argument is {\bf setf},
{\bf documentation} returns the documentation string of the setf generic
function associated with that name.
\label Values:
The documentation string associated with the given object is returned
unless none is available, in which case {\bf documentation} returns
{\bf nil}.
\label Remarks:
The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function object, method object, or class object.
\endcom
\begincom{get-method}\ftype{Generic function}
\label Purpose:
The generic function {\bf get-method} takes a generic function and returns the
method object that has the given method qualifiers
and parameter specializers.
\label Syntax:
\Defgen {get-method} {generic-function method-qualifiers specializers {\opt} errorp}
\label Arguments:
The {\it generic-function\/} argument is a generic function.
The {\it method-qualifiers\/} argument is a list of the
method qualifiers for the method. The order of the {\it method-qualifiers\/}
is significant.
The {\it specializers\/} argument is a list of the parameter
specializers for the method. It must correspond in length to the number
of required arguments of the generic function. This means that to
obtain the default method for a given generic function, a list of {\bf
t}'s corresponding in length to the number of required arguments of that
generic function must be given.
If there is no such method and the {\it errorp\/} argument is
unsupplied or is non-{\bf nil}, {\bf get-method} signals an error.
If there is no such method and the second argument is
{\bf nil}, {\bf get-method} returns {\bf nil}. The default value of
{\it errorp\/} is {\bf t}.
\label Values:
The result of {\bf get-method} is the method object with the given
method qualifiers and parameter specializers.
\endcom
\begincom{get-setf-generic-function}\ftype{Function}
\label Purpose:
The function {\bf get-setf-generic-function} takes a symbol for which
a setf generic function has been defined by either {\bf
defmethod-setf} or {\bf defgeneric-options-setf} and returns a generic
function object. This object is the generic function that is called
when the form {\tt (setf ({\it name arguments\/}) {\it new-value\/})} is
evaluated.
%[More details to be provided by Gregor.]
\label Syntax:
\Defun {get-setf-generic-function} {name}
\label Arguments:
The {\it name\/} argument is a symbol for which a setf generic
function has been defined. If no such setf generic function has been
defined, an error is signaled.
\label Values:
The function {\bf get-setf-generic-function} returns a generic function
object. This object is the generic function that is called
when the form {\tt (setf ({\it name arguments\/}) {\it new-value\/})} is
evaluated.
\endcom
\begincom{invalid-method-error}\ftype{Function}
\label Purpose:
The function {\bf invalid-method-error} reports an applicable method
whose qualifiers are not valid for the method combination type. The
error message is constructed by using a format string and any arguments to it.
Because an implementation may need to add additional contextual information
to the error message, {\bf invalid-method-error} should be called
only within the dynamic extent of a method-combination function.
Whether {\bf invalid-method-error} returns to its caller or throws to
the top level is implementation dependent.
\label Syntax:
\Defun {invalid-method-error} {method format-string {\rest} args}
\label Arguments:
The {\it method\/} argument is the invalid method object.
The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.
\label Remarks:
The function {\bf invalid-method-error} is called automatically when a
method fails to satisfy every qualifier pattern and predicate in a
{\bf define-method-combination} form.
A method combination function that
imposes additional restrictions should call {\bf invalid-method-error}
explicitly if it encounters a method it cannot accept.
The function {\bf invalid-method-error} will use the
condition-signaling system when and if it is incorporated into Common Lisp.
\label See Also:
{\bf define-method-combination}
\endcom
\begincom{make-generic-function}\ftype{Function}
\label Purpose:
The function {\bf make-generic-function} creates and returns a generic
function. This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.
\label Syntax:
\Defun {make-generic-function} {\key \vtop{\hbox{ :lambda-list :argument-precedence-order}
\hbox{ :declare :documentation :method-combination}
\hbox{ :generic-function-class :method-class}}}
\label Arguments:
The {\bf :lambda-list} argument is a lambda-list of the type that may be
given to {\bf defgeneric-options}.
The following arguments have the same semantics as the corresponding
arguments of {\bf defgeneric-options}, although their syntax may differ:
\beginlist
\item{\bull}
The {\bf :argument-precedence-order} argument is a list containing the
parameter names for all required arguments.
Each required argument must be included exactly once
so that the full and unambiguous precedence order is
supplied. If this condition is not met, an error is signaled.
\item{\bull}
The {\bf :method-combination} argument is a symbol or a list. If it
is a symbol, that symbol names a type of method combination. If it is
a list, its first element is a symbol that names a type of method
combination, and its remaining elements are any arguments accepted by
the method combination type. Any arguments that follow that symbol
depend on the type of method combination. Note that the standard
method combination type does not support any arguments. However, all
types of method combination defined by the short form of {\bf
define-method-combination} accept an optional argument named {\it
order\/}, which defaults to {\bf :most-specific-first}, where a value of {\bf
:most-specific-last} reverses the order of the primary methods
without affecting the order of the auxiliary methods.
\item{\bull}
The {\bf :documentation} argument is a string.
\item{\bull}
The {\bf :declare} argument is a list of declaration specifiers.
\item{\bull}
The {\bf :generic-function-class} argument is a class or the name of a class.
\item{\bull}
The {\bf :method-class} argument is a class or the name of a class.
\endlist
\eject
\label Values:
The result of {\bf make-generic-function} is a generic function object.
\label Remarks:
The function {\bf make-generic-function} is part of the
programmatic interface to {\bf defgeneric-options}.
\label See Also:
{\bf defgeneric-options}
\endcom
\begincom{make-instance}\ftype{Function}
\label Purpose:
The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.
\label Syntax:
\Defun {make-instance} {class {\rest} initialize-keywords-and-values}
\label Arguments:
The {\it class\/} argument is a class object or a symbol that names a class.
\label Values:
The new instance is returned.
\label Remarks:
The initialization protocol of {\bf make-instance} has not been specified.
It is not possible to make an instance of a class whose class is
{\bf standard-type-class} by using the function {\bf make-instance}.
If {\it class} is an instance of {\bf standard-type-class},
{\bf make-instance} signals an error.
The function {\bf class-of} can be used to determine the class of the
instance that is returned.
\label See Also:
{\bf class-of}
\endcom
\begincom{make-method}\ftype{Function}
\label Purpose:
The function {\bf make-method} creates and returns a method object.
\label Syntax:
\Defun {make-method} {method-qualifiers specializers function}
\label Arguments:
The {\it method-qualifiers\/} argument is a list of the method
qualifiers for the method.
The {\it specializers\/} argument is a list of the parameter
specializers for the method.
The {\it function\/} argument is the method function.
The length of the list of specializers must be equal to
the number of required arguments of the method function.
\label Values:
The function {\bf make-method} returns the resulting method object.
\label See Also:
{\bf defmethod
add-method}
\endcom
\begincom{make-method-call}\ftype{Function}
\label Purpose:
The function {\bf make-method-call} is used in method combination. It
has dynamic scope within the body of a {\bf define-method-combination}
form.
The function {\bf make-method-call} returns a form whose first element is
the operator specified by the {\bf :operator} keyword argument
(the default is {\bf progn}) and the rest of which is a list of forms that
call the methods in the given method list. Each method receives the same
arguments that the generic function received. The function
{\bf make-method-call} hides the implementation-dependent details of
how methods are called.
\label Syntax:
\Defun {make-method-call} {method-list\/ {\key :operator :identity-with-one-argument}}
\label Arguments:
Each element of {\it method-list\/} can be either a method object or a list.
When a list is given, it is regarded as a form and converted when necessary
into a method whose body is that form.
If the value of {\bf :identity-with-one-argument} is true and {\it
method-list\/} contains exactly one element, the result is simply a
form that calls that single method and does not invoke the
operator. If {\bf :operator} is {\bf progn}, the default for {\bf
:identity-with-one-argument} is true; otherwise the default for this
option is false. This option is to be used with operators that are
identity operators when applied to one argument, that is, such
operators as {\bf progn}, {\bf and}, {\bf $+$}, and {\bf max}. This
optimization can enable the use of an existing method as the
effective method, thus avoiding the need to create a new effective method.
If {\it method-list\/} is {\bf nil}, the result is a call to
the specified operator with no arguments or a form with the same effect.
If {\bf :operator} is {\bf :call-next-method}, the methods are
combined in a different way, rather than calling a function named
{\bf :call-next-method}. The result is a form that calls the first method and
arranges for {\bf call-next-method} to reach the rest of the methods in the
order in which they appear in {\it method-list}. If there is only one
method in {\it method-list}, the result is a form that calls that
method, and if the method calls {\bf call-next-method}, an error is signaled.
As a convenience, if {\it method-list\/} is a method object, it is
automatically converted to a one-element list of that method.
If {\bf call-next-method} is extended as noted, additional keyword
arguments will be needed for {\bf make-method-call}.
\eject
\label Values:
The result is a form whose first element is the operator specified by the
{\bf :operator} keyword argument and the rest of which is a list of forms
that call the methods in {\it method-list}.
\label See Also:
{\bf define-method-combination}
\endcom
\begincom{method-combination-error}\ftype{Function}
\label Purpose:
The function {\bf method-combination-error} reports a problem in
method combination. The error message is constructed by using a format
string and any arguments to it. Because an implementation may need to
add additional contextual information to the error message, {\bf
method-combination-error} should be called only within the dynamic
extent of a method combination function.
Whether {\bf method-combination-error} returns
to its caller or throws to the top level is implementation dependent.
\label Syntax:
\Defun {method-combination-error} {format-string {\rest} args}
\label Arguments:
The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.
\label Remarks:
The function {\bf method-combination-error} will use the condition
signaling system when and if it is incorporated into Common Lisp.
\label See Also:
{\bf define-method-combination}
\endcom
\begincom{method-qualifiers}\ftype{Function}
\label Purpose:
The function {\bf method-qualifiers} returns a list of the qualifiers of
the given method.
\label Syntax:
\Defun {method-qualifiers} {method}
\label Arguments:
The {\it method\/} argument is a method object.
\label Values:
A list of the qualifiers of the given method is returned.
\label Examples:
\screen!
(setq methods (remove-duplicates methods
:from-end t
:key #'method-qualifiers
:test #'equal))
\endscreen!
\label See Also:
{\bf define-method-combination}
\endcom
\begincom{multiple-value-prog2}\ftype{Macro}
\label Purpose:
The macro {\bf multiple-value-prog2} is similar to {\bf
multiple-value-prog1} except that it returns the values of its {\it second\/}
form.
\label Syntax:
\Defmac {multiple-value-prog2} {first second \star{\curly{form}}}
\label Values:
All the values of {\it second\/} are returned.
\label See Also:
{\bf define-method-combination}
\endcom
\begincom{print-object}\ftype{Generic function}
\label Purpose:
The generic function {\bf print-object} writes the printed
representation of an object to a stream. The function {\bf
print-object} is called by the print system; it should not be called
by the user.
Each implementation is required to provide a default method for {\bf
print-object}, that is, a method for the class {\bf t}. Implementations
are free to add methods for specific classes. Users can write methods
for {\bf print-object} for their own classes if they do not wish to
inherit an implementation-supplied method.
\label Syntax:
\Defgen {print-object} {object stream}
\label Arguments:
The first argument is any Lisp object. The second argument is a
stream; it cannot be {\bf t} or {\bf nil}.
\label Values:
The function {\bf print-object} returns its first argument, the object.
\label Remarks:
Methods for {\bf print-object} must obey the print control special
variables described in {\it Common Lisp: The Language}. The
specific details are the following:
\beginlist
\item{\bull}
Each method must implement {\bf *print-escape}*.
\item{\bull}
The {\bf *print-pretty*} control variable can be ignored
by most methods other than the one for lists.
\item{\bull}
The {\bf *print-circle*} control variable is handled by the printer
and can be ignored by methods.
\item{\bull}
The printer takes care of {\bf *print-level*} automatically, provided that
each method handles exactly one level of structure and
calls {\bf write} (or an equivalent function) recursively if
there are more structural levels. The printer's decision
of whether an object has components (and therefore should
not be printed when the printing depth is not less than
{\bf *print-level*}) is implementation dependent. In some
implementations its {\bf print-object} method is not called; in
others the method is called, and the determination that the
object has components is based on what it tries to write
to the stream.
\item{\bull}
Methods that produce output of indefinite length must obey
{\bf *print-length*}, but most methods other than the one for lists can
ignore it.
\item{\bull}
The {\bf *print-base*}, {\bf *print-radix*}, {\bf *print-case*}, {\bf
*print-gensym*}, and {\bf *print-array*} control variables apply
to specific types of objects and are handled by the methods for those
objects.
\endlist
In general, the printer and the {\bf print-object} methods should not
rebind the print control variables as they operate recursively through the
structure, but this is implementation dependent.
In some implementations the stream argument passed to a {\bf
print-object} method is not the original stream, but is an
intermediate stream that implements part of the printer. Methods
should therefore not depend on the identity of this stream.
All of the existing printing functions ({\bf write}, {\bf prin1}, {\bf
print}, {\bf princ}, {\bf pprint}, {\bf write-to-string}, {\bf
prin1-to-string}, {\bf princ-to-string}, the {\tt ~}{\bf S} and {\tt
~}{\bf A} format operations, and the {\tt ~}{\bf B}, {\tt ~}{\bf D},
{\tt ~}{\bf E}, {\tt ~}{\bf F}, {\tt ~}{\bf G}, {\tt ~}{\bf \$}, {\tt
~}{\bf O}, {\tt ~}{\bf R}, and {\tt ~}{\bf X} format operations when they
encounter a non-numeric value) are required to be changed to go
through the {\bf print-object} generic function. Each implementation is
required to replace its former implementation of printing with one or
more {\bf print-object} methods. Exactly which classes have methods for
{\bf print-object} is not specified; it would be valid for an implementation
to have one default method that is inherited by all system-defined
classes.
\endcom
\begincom{remove-method}\ftype{Generic function}
\label Purpose:
The generic function {\bf remove-method} removes a method from a
generic function. It destructively modifies the specified generic
function and returns the modified generic function as its result.
\label Syntax:
\Defgen {remove-method} {generic-function method {\opt} errorp}
\label Arguments:
The {\it generic-function\/} argument is a generic function
object.
The {\it method\/} argument is a method object.
If there is no such method and the {\it errorp\/} argument is
unsupplied or is non-{\bf nil}, {\bf remove-method} signals an error.
If there is no such method and the second argument is
{\bf nil}, {\bf remove-method} returns {\bf nil}. The default value of
{\it errorp\/} is {\bf t}.
\label Values:
The function {\bf remove-method} returns the modified generic
function.
\label See Also:
{\bf
get-method
add-method}
\endcom
\begincom{slot-value}\ftype{Function}
\label Purpose:
The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object. If there is no slot with that
name, an error is signaled.
The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot.
\label Syntax:
\Defun {slot-value} {object slot-name}
\endcom
\begincom{with-slots}\ftype{Macro}
\label Purpose:
The macro {\bf with-slots} creates a lexical context for referring to
slots as though they were variables. Within such a context the value
of the slot can be specified by using its slot name, as if it were a
lexically bound variable. Both {\bf setf} and {\bf setq} can be used
to set the value of the slot. The macro {\bf with-slots} can be used
inside a method or inside any function.
The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to the accessor generated by {\bf defclass}
unless the {\bf :use-accessors} argument is {\bf nil}, in which
case {\bf slot-value} is used instead of the accessor.
\label Syntax:
\Defmac {with-slots} {\paren {\star{\curly{instance-form $\vert$ \paren{instance-form \star{option}}}}} \star{\form}}
{\it option\/}::$=$ {\tt\vtop{\hbox{:use-accessors {\it flag\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it symbol\/}}}}
\label Arguments:
The {\it instance-form\/} should evaluate to an object that has slots,
such as an instance of a user-defined class. The {\it instance-form\/}
should not evaluate to an instance of a standard type class.
Each {\it instance-form\/} is evaluated exactly once, upon entry to the
body of the {\bf with-slots} form. The {\it instance-form\/} forms
are evaluated in the order in which they appear.
It is necessary that the class of the instance can be determined lexically
(at compile-time).
Either {\it instance-form\/} must be the name of a specialized parameter in
the lambda-list of a method that lexically contains this {\bf with-slots}
form, or the {\bf :class} option must be used to indicate the class of
the instance.
The keyword options in this special form are not evaluated.
\beginlist
\item{\bull}
The {\bf :class} option is used to specify the class or a superclass
of the instance. Its argument is the name of a class. This option is
necessary if the class of the instance cannot be determined from the
lambda-list of a method that lexically contains the {\bf with-slots}
form or if the {\bf with-slots} form does not occur within a method
body. If the {\bf :class} option is used, an error is signaled
at runtime if the
class of the instance is not a subclass of the specified class. Note that
if a superclass of the instance is given here, only those slots accessible
in instances of the superclass are accessible; this might be a different set
of slots than those accessible in the instance itself.
\item{\bull}
The {\bf :prefix} option is used to generate a variable name by which
the given slot may be referenced.
This name is given by the name of {\it symbol\/} followed by the slot
name. It causes a symbol of the given name to be created and interned
in the package that is current at the time the {\bf with-slots} form is
macro-expanded.
This option can be used to keep separate two instances whose slot names
overlap, such as two instances of the same class or two instances that
have a common superclass.
\item{\bull}
The {\bf :use-accessors} option is used to specify whether accessing a
slot is performed by using the accessor function generated by {\bf
defclass} or by calling the function {\bf slot-value}. If {\bf
:use-accessors} is {\bf t}, the accessor function generated by {\bf
defclass} is used to access the slots; this means that any methods
written for the accessor are also run. If {\bf :use-accessors} is
{\bf nil}, {\bf with-slots} accesses the slots by using {\bf slot-value}
instead of the accessor. If accessors for the slot were not specified
in the relevant {\bf defclass} form, then the value of {\bf
:use-accessors} should be specified as {\bf nil}. The default value
of {\bf :use-accessors} is {\bf t}.
\endlist
\label Values:
The value of the {\bf with-slots} form is the value returned by
the last form in its body.
\label Examples:
\screen!
(defclass point () ((x 0) (y 0))
(:accessor-prefix point-))
(defmethod move ((p point) dx dy)
(with-slots (p) ; p is known as a point from the method args
(setf x (+ x dx) y (+ y dy)))) ; use accessor functions
(defmethod move ((p point) dx dy)
(with-slots ((p :use-accessors nil))
(setf x (+ x dx) y (+ y dy)))) ; use slot-value
(defmethod make-same-height ((p1 point) (p2 point))
;; use :prefix to make distinction between the two points
(with-slots ((p1 :prefix p1-) (p2 :prefix p2-))
(setf p1-y p2-y)))
(defmethod make-horizontal ((l line))
;; it is necessary to specify the class of point explicitly,
;; because there is no lexical way to determine it
(with-slots (((left-point l) :class point :prefix left-)
((right-point l) :class point :prefix right-))
(setf left-y right-y)))
\endscreen!
\eject
\label Remarks:
The examples have used {\bf setf} to change the value of instance
variables; {\bf setq} is also allowed.
An error is signaled if the class of {\it instance-form} cannot be inferred
from the lexical context in which it occurs and the {\bf :class} option
is not specified.
An error is signaled if there is any conflict between variable names.
\endcom
\endChapter
\bye